.. _inferenceyamlconfigchangelog:
Changelog of the Inference YAML Configuration
=============================================
Version 8
---------
This version removes the ``Sampling`` section from the configuration file.
The ``Sampling`` section was used to specify the splitting and recombination strategy for the input image, in cases where the input image are too large to be processed in a single pass.
This is now handled by dedicated operations that can be specified more flexibly in the ``PreProcessing`` and ``PostProcessing`` sections respectively.
More specifically, the ``SplitIntoPatches`` operation is used to split the input image into patches, while the ``RecombinePatches`` operation is used to recombine the patches into a single prediction image.
When the input image needs to be padded to a multiple of the ``DimensionDivisor``, the ``PadToNextMultiple`` operation is used to pad the input image.
When the model prediction needs to be unpadded, the ``Inverse`` operation is used to remove the padding from the model prediction.
.. warning::
The new mechanism uses a more efficient splitting and recombination logic, which can lead to slightly different final predictions.
As such, upgrading a configuration file to version 8 is a **breaking change** for existing models.
In order to prevent unwanted regressions, the yaml configuration file for existing models **is not automatically updated** to version 8.
If you want to let the yaml configuration file be updated automatically to version 8, you need to **manually set** the flag ``UpgradeToMLModelV2: true`` (default is ``false``).
Upgrading to version 8 will automatically remove any specified ``Sampling`` section and convert it to the
corresponding pre- and post-processing operations.
In particular, the following logic is applied:
- If ``Sampling.MaxSizeSubdivision`` was set, the ``SplitIntoPatches`` operation is appended to the ``PreProcessing`` section and the ``RecombinePatches`` operation is inserted as first operation in the ``PostProcessing`` section.
- If ``Sampling.MaxSizeSubdivision`` was not set and ``Sampling.DimensionDivisor`` was set, a ``PadToNextMultiple`` operation is added to the ``PreProcessing`` section.
- If ``DimensionDivisor`` was set together with ``MaxSizeSubdivision``, it is checked that ``MaxSizeSubdivision`` is a multiple of the ``DimensionDivisor``, but no extra padding is added to the PreProcessing.
- ``Sampling.PaddingMode`` is used to configure any potential padding of the input image.
- ``Sampling.RecombineWeighted`` and ``Sampling.RecombineDevice`` are used to configure the recombination of the patches.
- Any other parameter of the ``Sampling`` section not mentioned above is ignored.
Example 1
~~~~~~~~~
The following configuration example with splitting and recombination:
.. code-block:: yaml
Version: 7
PreProcessing:
...
PostProcessing:
...
Sampling:
- DimensionDivisor: 32
- MaxSizeSubdivision: 96
- PixelsOverlap: 16
- RecombineWeighted: true
- PaddingMode: Mirror
is converted to:
.. code-block:: yaml
Version: 8
PreProcessing:
... # operations from previous version
- SplitIntoPatches:
patch_size: [96, 96, 96]
patch_step_size: 1.0
device: GPUIfOpenGL # or ForceCPU
PostProcessing:
- RecombinePatches:
device: GPUIfOpenGL # or ForceCPU
mode: Weighted
... # operations from previous version
Example 2
~~~~~~~~~
The following configuration example with padding and unpadding:
.. code-block:: yaml
Version: 7
PreProcessing:
...
PostProcessing:
...
Sampling:
- DimensionDivisor: 32
- MaxSizeSubdivision: -1
- PixelsOverlap: 16
- PaddingMode: Mirror
- SkipUnpadding: false
is converted to:
.. code-block:: yaml
Version: 8
PreProcessing:
... # operations from previous version
- PadToNextMultiple: # new operation for padding the input image to a multiple of the DimensionDivisor
dimension_divisor: 32
padding_mode: Mirror
allow_dimension_change: false
record_identifier: pad_to_next_dim_ev7to8_1 # identifier of the padding operation, used to identify which operation instance to inverse in the PostProcessing
PostProcessing:
- Inverse: # new operation for removing the padding from the model prediction
target_identifier: pad_to_next_dim_ev7to8_1 # identifier of the target operation to be inverted
... # operations from previous version
.. note::
To update an old configuration file to the latest version, you can load it by instantiating a ``ModelConfiguration`` object and then use the :cpp:func:`ModelConfiguration::save` function to save it to disk. The ``save`` function will write a configuration file with the latest version.
If you need to bulk upgrade a large number of configurations, you can use the convenience function ``imfusion.machinelearning.update_model_configuration`` in the ``imfusion-sdk`` python package, or use it directly from the command line with
``python -m imfusion.machinelearning.update_model_configuration --input --output